home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / close.z / close
Encoding:
Text File  |  2002-10-03  |  11.3 KB  |  198 lines
  1.  
  2.  
  3.  
  4. cccclllloooosssseeee((((DDDD2222))))                                                            cccclllloooosssseeee((((DDDD2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _cccc_llll_oooo_ssss_eeee - relinquish access to a device
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSyyyynnnnooooppppssssiiiissss
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_eeee_rrrr_rrrr_nnnn_oooo_...._hhhh_>>>>
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_oooo_pppp_eeee_nnnn_...._hhhh_>>>>
  17.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_cccc_rrrr_eeee_dddd_...._hhhh_>>>>
  18.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  19.      _iiii_nnnn_tttt _p_r_e_f_i_x_cccc_llll_oooo_ssss_eeee_((((_dddd_eeee_vvvv______tttt _d_e_v_,,,, _iiii_nnnn_tttt _f_l_a_g_,,,, _iiii_nnnn_tttt _o_t_y_p_,,,, _cccc_rrrr_eeee_dddd______tttt _****_c_r_p_))))_;;;;
  20.  
  21.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr AAAArrrrgggguuuummmmeeeennnnttttssss
  22.      _d_e_v       Device number.
  23.  
  24.      _f_l_a_g      File status flags.
  25.  
  26.      _o_t_y_p      Parameter supplied so that the driver can determine how many
  27.                times a device was opened and for what reasons.
  28.  
  29.      _c_r_p       Pointer to the user credential structure.
  30.  
  31.    SSSSTTTTRRRREEEEAAAAMMMMSSSS SSSSyyyynnnnooooppppssssiiiissss
  32.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  33.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>>
  34.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ffff_iiii_llll_eeee_...._hhhh_>>>>
  35.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_eeee_rrrr_rrrr_nnnn_oooo_...._hhhh_>>>>
  36.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_cccc_rrrr_eeee_dddd_...._hhhh_>>>>
  37.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  38.      _iiii_nnnn_tttt _p_r_e_f_i_x_cccc_llll_oooo_ssss_eeee_((((_qqqq_uuuu_eeee_uuuu_eeee______tttt _****_q, _iiii_nnnn_tttt _f_l_a_g, _cccc_rrrr_eeee_dddd______tttt _****_c_r_p_))))_;;;;
  39.  
  40.    SSSSTTTTRRRREEEEAAAAMMMMSSSS AAAArrrrgggguuuummmmeeeennnnttttssss
  41.      _q         Pointer to queue used to reference the read side of the driver.
  42.  
  43.      _f_l_a_g      File status flag.
  44.  
  45.      _c_r_p       Pointer to the user credential structure.
  46.  
  47. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  48.    BBBBlllloooocccckkkk aaaannnndddd CCCChhhhaaaarrrraaaacccctttteeeerrrr DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  49.      The _cccc_llll_oooo_ssss_eeee routine ends the connection between the user process and the
  50.      device, and prepares the device (hardware and software) so that it is
  51.      ready to be opened again.
  52.  
  53.      Valid values for _f_l_a_g and their definitions can be found in _oooo_pppp_eeee_nnnn(D2).
  54.  
  55.      The values for _o_t_y_p are mutually exclusive:
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. cccclllloooosssseeee((((DDDD2222))))                                                            cccclllloooosssseeee((((DDDD2222))))
  70.  
  71.  
  72.  
  73.           _OOOO_TTTT_YYYY_PPPP______BBBB_LLLL_KKKK    Close was through the block interface for the device.
  74.  
  75.           _OOOO_TTTT_YYYY_PPPP______CCCC_HHHH_RRRR    Close was through the raw/character interface for the
  76.                       device.
  77.  
  78.           _OOOO_TTTT_YYYY_PPPP______LLLL_YYYY_RRRR    Close a layered device.  This flag is used when one
  79.                       driver calls another driver's _cccc_llll_oooo_ssss_eeee routine.
  80.  
  81.      For _OOOO_TTTT_YYYY_PPPP______BBBB_LLLL_KKKK and _OOOO_TTTT_YYYY_PPPP______CCCC_HHHH_RRRR, a device may be opened simultaneously by
  82.      multiple processes and the driver _oooo_pppp_eeee_nnnn routine is called for each open,
  83.      but the kernel will only call the _cccc_llll_oooo_ssss_eeee routine when the last process
  84.      using the device issues a _cccc_llll_oooo_ssss_eeee(2) system call or exits.
  85.  
  86.      There is one exception to this rule.  If a device is opened through both
  87.      its character and its block interfaces, then there will be one close per
  88.      interface.  For example, if the same device is opened twice through its
  89.      block interface and three times through its character interface, then
  90.      there will be two calls to the driver's close routine; one when the block
  91.      interface is finished being used, and one when the character interface is
  92.      finished being used.
  93.  
  94.      For _OOOO_TTTT_YYYY_PPPP______LLLL_YYYY_RRRR, there will be one such close for every corresponding open.
  95.      Here, the driver should count each open and close based on the _o_t_y_p
  96.      parameter to determine when the device should really be closed.
  97.  
  98.    SSSSTTTTRRRREEEEAAAAMMMMSSSS DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  99.      The _cccc_llll_oooo_ssss_eeee routines of STREAMS drivers and modules are called when a
  100.      stream is dismantled or a module popped.  The steps for dismantling a
  101.      stream are performed in the following order.  First, any non-persistent
  102.      multiplexor links present are unlinked and the lower streams are closed.
  103.      Next, the following steps are performed for each module or driver on the
  104.      stream, starting at the head and working toward the tail:
  105.  
  106.           1.  The write queue is given a chance to drain.
  107.  
  108.           2.  Interrupts from STREAMS devices are blocked.
  109.  
  110.           3.  The _cccc_llll_oooo_ssss_eeee routine is called.
  111.  
  112.           4.  The module or driver is removed from the stream.
  113.  
  114.           5.  Any remaining messages on the queues are freed.
  115.  
  116.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  117.      The _cccc_llll_oooo_ssss_eeee routine should return 0 for success, or the appropriate error
  118.      number.  Refer to _eeee_rrrr_rrrr_nnnn_oooo_ssss(D5) for a list of DDI/DKI error numbers.  Return
  119.      errors rarely occur, but if a failure is detected, the driver should
  120.      still close the device and then decide whether the severity of the
  121.      problem warrants displaying a message on the console.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. cccclllloooosssseeee((((DDDD2222))))                                                            cccclllloooosssseeee((((DDDD2222))))
  136.  
  137.  
  138.  
  139. UUUUSSSSAAAAGGGGEEEE
  140.      This entry point is required in all drivers and STREAMS modules.
  141.  
  142.      A _cccc_llll_oooo_ssss_eeee routine could perform any of the following general functions,
  143.      depending on the type of device and the service provided:
  144.  
  145.           disable device interrupts
  146.  
  147.           hang up phone lines
  148.  
  149.           rewind a tape
  150.  
  151.           deallocate buffers from a private buffering scheme
  152.  
  153.           unlock an unsharable device (that was locked in the _oooo_pppp_eeee_nnnn routine)
  154.  
  155.           flush buffers
  156.  
  157.           notify a device of the close
  158.  
  159.           cancel any pending timeout or bufcall routines that access data that
  160.           are deinitialized or deallocated during close
  161.  
  162.           deallocate any resources allocated on open
  163.  
  164.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  165.      The _cccc_llll_oooo_ssss_eeee routine has user context and can sleep.  However, STREAMS
  166.      drivers and modules must sleep such that signals do not cause the sleep
  167.      to longjump [see _ssss_llll_eeee_eeee_pppp(D3)].  Also, if a _cccc_llll_oooo_ssss_eeee routine does sleep, it is
  168.      important that the driver writer synchronize the driver's _oooo_pppp_eeee_nnnn and _cccc_llll_oooo_ssss_eeee
  169.      routines, since a driver can be reopened while being closed.
  170.  
  171.      If the _FFFF_NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or _FFFF_NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK flags are specified in the _f_l_a_g argument, the
  172.      driver should try to avoid sleeping, if possible, during close
  173.      processing.
  174.  
  175. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  176.      _dddd_rrrr_vvvv______pppp_rrrr_iiii_vvvv(D3), _eeee_rrrr_rrrr_nnnn_oooo_ssss(D5), _oooo_pppp_eeee_nnnn(D2), _qqqq_uuuu_eeee_uuuu_eeee(D4), _uuuu_nnnn_bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3),
  177.      _uuuu_nnnn_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt(D3), _ssss_llll_eeee_eeee_pppp(D3)
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                         PPPPaaaaggggeeee 3333
  195.  
  196.  
  197.  
  198.